How to create filters

Filters, which are programs or scripts, reside under the etc/exports or local/etc/exports directory on the Vitalware server.

They may be module specific or may be applicable to all modules. Module specific filters are stored under a sub-directory named after the module to which they apply. For example, Parties module specific filters would be located under etc/exports/eparties or local/etc/exports/eparties.

Note: When adding your own filters to the Vitalware server, they should be placed under local/etc/exports as etc/exports is reserved for use by Vitalware upgrades.

The name of the file containing the program or script is the label displayed in the Filters drop list when specifying a new Scheduled Export.

When an export is performed the initial data export is in Vitalware XML format. The data is placed in a temporary file on the Vitalware server and passed as an argument to the filter specified for the Scheduled Export. The filter receives only one argument, the name of the file containing the exported data.

Several environment variables are set and available to the filter when it executes:

If the filter is unable to process the exported data, any error messages should be written to STDERR and the export terminated with a non-zero exit status. This notifies Vitalware that the filter did not complete successfully and an export failure is recorded. Any text written to STDERR is displayed in the Filter Output box for an Exports record in the Exports module.

Once the filter has processed the export data it should print out to STDOUT a list of all the files generated. These files are moved under the logs/exports directory on the Vitalware server. The file names are displayed in the Export Files table in the Exports record created. If the filter completed successfully, it should return a zero exit status.

The filter may manipulate the export data in any way required. It may email the data (via sendmail), print it (via lpr or lp) or even send it to remote machines (via rsh or ssh). A copy of the data exported should always be attached to the Export record so it can be reviewed at a later date, if required.

In this example filter we convert the export data from XML to CSV (Comma Separated Values) and email the file(s) produced to a mail alias address (csvexport@client.org) on our local mail server. The mail server will then forward the email onto a host of recipients.

We can use texxmlodbc to convert the export XML to CSV files. The filter is written using the perl scripting language as it provides a nice package for sending multi-part email messages.

The filter is:

#!/usr/bin/perl

use strict;

use warnings 'all';

use MIME::Lite;

#

#  First we convert the Vitalware XML to CSV and save

#  the list of files generated.

#

if (! open(FILES, "texxmlodbc --output-encoding=iso-8859-1 '$ARGV[0]' |"))

{

        print STDERR "Cannot execute texxmlodbc";

        exit(1);

}

my @files = <FILES>;

close(FILES);

#

#  Build up the message to send.

#

my $body = <<END;

The attached files were generated by the Vitalware Scheduled Export facility.

The details of the export are:

Title: $ENV{EXPORTTITLE}

Module: $ENV{EXPORTTABLE}

Start Date: $ENV{EXPORTSTARTDATE}

End Date: $ENV{EXPORTENDDATE}

END

#

#  Create an email message to csvexport@client.org

#

my $msg = MIME::Lite->new(

        To      => 'csvexport@client.org',

        Subject => 'Vitalware Scheduled Export CSV Files',

        Type    => 'multipart/mixed'

);

#

#  Add the email text first.

#

$msg->attach(

        Type    => 'TEXT',

        Data    => $body

);

#

#  Add each file.

#

foreach my $file (@files)

{

        #

        #  Figure out the file mime type and attach it

        #

        chomp($file);

        my $type = ($file =~ /\.ini$/i) ? 'TEXT' : 'text/csv';

        $msg->attach(

                Type            => $type,

                Path            => $file,

                Disposition     => 'attachment'

);

}

#

#  Send the email.

#

if (! $msg->send())

{

        print STDERR 'Cannot send email to csvexport@client.org';

        exit(1);

}

print STDERR 'Email sent to csvexport@client.org successfully';

#

#  Output the file list for the export record.

#

print join("\n", @files);

exit(0);

Notice how the filter outputs the names of the CSV files at the end so they can be attached to the Export record created. Once attached these files may be reviewed at any time.